<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">


<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    
    <title>Authentication &mdash; Requests 2.3.0 documentation</title>
    
    <link rel="stylesheet" href="../_static/flasky.css" type="text/css" />
    <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
    
    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
        URL_ROOT:    '../',
        VERSION:     '2.3.0',
        COLLAPSE_INDEX: false,
        FILE_SUFFIX: '.html',
        HAS_SOURCE:  true
      };
    </script>
    <script type="text/javascript" src="../_static/jquery.js"></script>
    <script type="text/javascript" src="../_static/underscore.js"></script>
    <script type="text/javascript" src="../_static/doctools.js"></script>
    <link rel="top" title="Requests 2.3.0 documentation" href="../index.html" />
    <link rel="next" title="Frequently Asked Questions" href="../community/faq.html" />
    <link rel="prev" title="Advanced Usage" href="advanced.html" />
   
  
  <meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9">
  <script type="text/javascript" src="https://gumroad.com/js/gumroad.js"></script>

  </head>
  <body>
    <div class="related">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="../genindex.html" title="General Index"
             accesskey="I">index</a></li>
        <li class="right" >
          <a href="../py-modindex.html" title="Python Module Index"
             >modules</a> |</li>
        <li class="right" >
          <a href="../community/faq.html" title="Frequently Asked Questions"
             accesskey="N">next</a> |</li>
        <li class="right" >
          <a href="advanced.html" title="Advanced Usage"
             accesskey="P">previous</a> |</li>
        <li><a href="../index.html">Requests 2.3.0 documentation</a> &raquo;</li> 
      </ul>
    </div>  

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body">
            
  <div class="section" id="authentication">
<span id="id1"></span><h1>Authentication<a class="headerlink" href="#authentication" title="Permalink to this headline">¶</a></h1>
<p>This document discusses using various kinds of authentication with Requests.</p>
<p>Many web services require authentication, and there are many different types.
Below, we outline various forms of authentication available in Requests, from
the simple to the complex.</p>
<div class="section" id="basic-authentication">
<h2>Basic Authentication<a class="headerlink" href="#basic-authentication" title="Permalink to this headline">¶</a></h2>
<p>Many web services that require authentication accept HTTP Basic Auth. This is
the simplest kind, and Requests supports it straight out of the box.</p>
<p>Making requests with HTTP Basic Auth is very simple:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">requests.auth</span> <span class="kn">import</span> <span class="n">HTTPBasicAuth</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">requests</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s">&#39;https://api.github.com/user&#39;</span><span class="p">,</span> <span class="n">auth</span><span class="o">=</span><span class="n">HTTPBasicAuth</span><span class="p">(</span><span class="s">&#39;user&#39;</span><span class="p">,</span> <span class="s">&#39;pass&#39;</span><span class="p">))</span>
<span class="go">&lt;Response [200]&gt;</span>
</pre></div>
</div>
<p>In fact, HTTP Basic Auth is so common that Requests provides a handy shorthand
for using it:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">requests</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s">&#39;https://api.github.com/user&#39;</span><span class="p">,</span> <span class="n">auth</span><span class="o">=</span><span class="p">(</span><span class="s">&#39;user&#39;</span><span class="p">,</span> <span class="s">&#39;pass&#39;</span><span class="p">))</span>
<span class="go">&lt;Response [200]&gt;</span>
</pre></div>
</div>
<p>Providing the credentials in a tuple like this is exactly the same as the
<tt class="docutils literal"><span class="pre">HTTPBasicAuth</span></tt> example above.</p>
<div class="section" id="netrc-authentication">
<h3>netrc Authentication<a class="headerlink" href="#netrc-authentication" title="Permalink to this headline">¶</a></h3>
<p>If no authentication method is given with the <tt class="docutils literal"><span class="pre">auth</span></tt> argument, Requests will
attempt to get the authentication credentials for the URL&#8217;s hostname from the
user&#8217;s netrc file.</p>
<p>If credentials for the hostname are found, the request is sent with HTTP Basic
Auth.</p>
</div>
</div>
<div class="section" id="digest-authentication">
<h2>Digest Authentication<a class="headerlink" href="#digest-authentication" title="Permalink to this headline">¶</a></h2>
<p>Another very popular form of HTTP Authentication is Digest Authentication,
and Requests supports this out of the box as well:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">requests.auth</span> <span class="kn">import</span> <span class="n">HTTPDigestAuth</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">url</span> <span class="o">=</span> <span class="s">&#39;http://httpbin.org/digest-auth/auth/user/pass&#39;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">requests</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="n">url</span><span class="p">,</span> <span class="n">auth</span><span class="o">=</span><span class="n">HTTPDigestAuth</span><span class="p">(</span><span class="s">&#39;user&#39;</span><span class="p">,</span> <span class="s">&#39;pass&#39;</span><span class="p">))</span>
<span class="go">&lt;Response [200]&gt;</span>
</pre></div>
</div>
</div>
<div class="section" id="oauth-1-authentication">
<h2>OAuth 1 Authentication<a class="headerlink" href="#oauth-1-authentication" title="Permalink to this headline">¶</a></h2>
<p>A common form of authentication for several web APIs is OAuth. The <tt class="docutils literal"><span class="pre">requests-oauthlib</span></tt>
library allows Requests users to easily make OAuth authenticated requests:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">requests</span>
<span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">requests_oauthlib</span> <span class="kn">import</span> <span class="n">OAuth1</span>

<span class="gp">&gt;&gt;&gt; </span><span class="n">url</span> <span class="o">=</span> <span class="s">&#39;https://api.twitter.com/1.1/account/verify_credentials.json&#39;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">auth</span> <span class="o">=</span> <span class="n">OAuth1</span><span class="p">(</span><span class="s">&#39;YOUR_APP_KEY&#39;</span><span class="p">,</span> <span class="s">&#39;YOUR_APP_SECRET&#39;</span><span class="p">,</span>
<span class="go">                  &#39;USER_OAUTH_TOKEN&#39;, &#39;USER_OAUTH_TOKEN_SECRET&#39;)</span>

<span class="gp">&gt;&gt;&gt; </span><span class="n">requests</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="n">url</span><span class="p">,</span> <span class="n">auth</span><span class="o">=</span><span class="n">auth</span><span class="p">)</span>
<span class="go">&lt;Response [200]&gt;</span>
</pre></div>
</div>
<p>For more information on how to OAuth flow works, please see the official <a class="reference external" href="http://oauth.net/">OAuth</a> website.
For examples and documentation on requests-oauthlib, please see the <a class="reference external" href="https://github.com/requests/requests-oauthlib">requests_oauthlib</a>
repository on GitHub</p>
</div>
<div class="section" id="other-authentication">
<h2>Other Authentication<a class="headerlink" href="#other-authentication" title="Permalink to this headline">¶</a></h2>
<p>Requests is designed to allow other forms of authentication to be easily and
quickly plugged in. Members of the open-source community frequently write
authentication handlers for more complicated or less commonly-used forms of
authentication. Some of the best have been brought together under the
<a class="reference external" href="https://github.com/requests">Requests organization</a>, including:</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/requests/requests-kerberos">Kerberos</a></li>
<li><a class="reference external" href="https://github.com/requests/requests-ntlm">NTLM</a></li>
</ul>
<p>If you want to use any of these forms of authentication, go straight to their
GitHub page and follow the instructions.</p>
</div>
<div class="section" id="new-forms-of-authentication">
<h2>New Forms of Authentication<a class="headerlink" href="#new-forms-of-authentication" title="Permalink to this headline">¶</a></h2>
<p>If you can&#8217;t find a good implementation of the form of authentication you
want, you can implement it yourself. Requests makes it easy to add your own
forms of authentication.</p>
<p>To do so, subclass <a class="reference internal" href="../api.html#requests.auth.AuthBase" title="requests.auth.AuthBase"><tt class="xref py py-class docutils literal"><span class="pre">AuthBase</span></tt></a> and implement the
<tt class="docutils literal"><span class="pre">__call__()</span></tt> method:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">requests</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">class</span> <span class="nc">MyAuth</span><span class="p">(</span><span class="n">requests</span><span class="o">.</span><span class="n">auth</span><span class="o">.</span><span class="n">AuthBase</span><span class="p">):</span>
<span class="gp">... </span>    <span class="k">def</span> <span class="nf">__call__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">r</span><span class="p">):</span>
<span class="gp">... </span>        <span class="c"># Implement my authentication</span>
<span class="gp">... </span>        <span class="k">return</span> <span class="n">r</span>
<span class="gp">...</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">url</span> <span class="o">=</span> <span class="s">&#39;http://httpbin.org/get&#39;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">requests</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="n">url</span><span class="p">,</span> <span class="n">auth</span><span class="o">=</span><span class="n">MyAuth</span><span class="p">())</span>
<span class="go">&lt;Response [200]&gt;</span>
</pre></div>
</div>
<p>When an authentication handler is attached to a request,
it is called during request setup. The <tt class="docutils literal"><span class="pre">__call__</span></tt> method must therefore do
whatever is required to make the authentication work. Some forms of
authentication will additionally add hooks to provide further functionality.</p>
<p>Further examples can be found under the <a class="reference external" href="https://github.com/requests">Requests organization</a> and in the
<tt class="docutils literal"><span class="pre">auth.py</span></tt> file.</p>
</div>
</div>


          </div>
        </div>
      </div>
      <div class="sphinxsidebar">
        <div class="sphinxsidebarwrapper"><p class="logo">
  <a href="../index.html">
    <img class="logo" src="../_static/requests-sidebar.png" title="Rezzy the Requests Sea Turtle"/>
  </a>
</p>
<p>
<iframe src="http://ghbtns.com/github-btn.html?user=kennethreitz&repo=requests&type=watch&count=true&size=large"
  allowtransparency="true" frameborder="0" scrolling="0" width="200px" height="35px"></iframe>
</p>

<p>
  Requests is an elegant and simple HTTP library for Python, built for
  human beings. You are currently looking at the documentation of the
  development release.
</p>


<h3>Donate</h3>
 <p>
     If you love Requests, consider supporting the author <a href="https://www.gittip.com/kennethreitz/">on Gittip</a>:
 </p>
 <p>
   <iframe style="border: 0; margin: 0; padding: 0;"
       src="https://www.gittip.com/kennethreitz/widget.html"
       width="48pt" height="20pt"></iframe>
 </p>

<h3>Get Updates</h3>
<p>Receive updates on new releases and upcoming projects.</p>

<p><a href="http://tinyletter.com/kennethreitz">Subscribe to Newsletter</a></p>


  <h3><a href="../index.html">Table Of Contents</a></h3>
  <ul>
<li><a class="reference internal" href="#">Authentication</a><ul>
<li><a class="reference internal" href="#basic-authentication">Basic Authentication</a><ul>
<li><a class="reference internal" href="#netrc-authentication">netrc Authentication</a></li>
</ul>
</li>
<li><a class="reference internal" href="#digest-authentication">Digest Authentication</a></li>
<li><a class="reference internal" href="#oauth-1-authentication">OAuth 1 Authentication</a></li>
<li><a class="reference internal" href="#other-authentication">Other Authentication</a></li>
<li><a class="reference internal" href="#new-forms-of-authentication">New Forms of Authentication</a></li>
</ul>
</li>
</ul>
<h3>Related Topics</h3>
<ul>
  <li><a href="../index.html">Documentation overview</a><ul>
      <li>Previous: <a href="advanced.html" title="previous chapter">Advanced Usage</a></li>
      <li>Next: <a href="../community/faq.html" title="next chapter">Frequently Asked Questions</a></li>
  </ul></li>
</ul>
<div id="searchbox" style="display: none">
  <h3>Quick search</h3>
    <form class="search" action="../search.html" method="get">
      <input type="text" name="q" />
      <input type="submit" value="Go" />
      <input type="hidden" name="check_keywords" value="yes" />
      <input type="hidden" name="area" value="default" />
    </form>
    <p class="searchtip" style="font-size: 90%">
    Enter search terms or a module, class or function name.
    </p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
        </div>
      </div>
      <div class="clearer"></div>
    </div>
    <div class="footer">
      &copy; Copyright 2014. A <a href="http://kennethreitz.com/pages/open-projects.html">Kenneth Reitz</a> Project.
    </div>
    <a href="https://github.com/kennethreitz/requests" class="github">
        <img style="position: absolute; top: 0; right: 0; border: 0;" src="http://s3.amazonaws.com/github/ribbons/forkme_right_darkblue_121621.png" alt="Fork me on GitHub"  class="github"/>
    </a>
    <script type="text/javascript">
    /* <![CDATA[ */
        (function() {
            var s = document.createElement('script'), t = document.getElementsByTagName('script')[0];
            s.type = 'text/javascript';
            s.async = true;
            s.src = 'http://api.flattr.com/js/0.6/load.js?mode=auto';
            t.parentNode.insertBefore(s, t);
        })();
    /* ]]> */
    </script>
        <script type="text/javascript">
    setTimeout(function(){var a=document.createElement("script");
    var b=document.getElementsByTagName("script")[0];
    a.src=document.location.protocol+"//dnn506yrbagrg.cloudfront.net/pages/scripts/0013/7219.js?"+Math.floor(new Date().getTime()/3600000);
    a.async=true;a.type="text/javascript";b.parentNode.insertBefore(a,b)}, 1);
    </script>

    <script type="text/javascript">
        new HelloBar(36402,48802);
    </script>


    <script type="text/javascript">

      var _gaq = _gaq || [];
      _gaq.push(['_setAccount', 'UA-8742933-11']);
      _gaq.push(['_setDomainName', 'none']);
      _gaq.push(['_setAllowLinker', true]);
      _gaq.push(['_trackPageview']);

      (function() {
        var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
        ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
        var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
      })();

    </script>

    <script type="text/javascript">
      (function() {
        var t   = document.createElement('script');
        t.type  = 'text/javascript';
        t.async = true;
        t.id    = 'gauges-tracker';
        t.setAttribute('data-site-id',
                       '4ddc27f6613f5d186d000007');
        t.src = '//secure.gaug.es/track.js';
        var s = document.getElementsByTagName('script')[0];
        s.parentNode.insertBefore(t, s);
      })();
    </script>
  </body>
</html>